namespace hao_Common.Http.Interfaces
{
    /// <summary>
    /// HTTP请求助手接口
    /// 提供简单易用的HTTP请求方法
    /// </summary>
    public interface IHttpHelper
    {
        /// <summary>
        /// 发送GET请求
        /// </summary>
        /// <typeparam name="T">响应数据类型</typeparam>
        /// <param name="url">请求URL</param>
        /// <param name="headers">请求头</param>
        /// <param name="cancellationToken">取消令牌</param>
        /// <returns>响应数据</returns>
        Task<T?> GetAsync<T>(string url, Dictionary<string, string>? headers = null, CancellationToken cancellationToken = default);

        /// <summary>
        /// 发送GET请求并返回字符串
        /// </summary>
        /// <param name="url">请求URL</param>
        /// <param name="headers">请求头</param>
        /// <param name="cancellationToken">取消令牌</param>
        /// <returns>响应字符串</returns>
        Task<string> GetStringAsync(string url, Dictionary<string, string>? headers = null, CancellationToken cancellationToken = default);

        /// <summary>
        /// 发送POST请求
        /// </summary>
        /// <typeparam name="T">响应数据类型</typeparam>
        /// <param name="url">请求URL</param>
        /// <param name="data">请求数据</param>
        /// <param name="headers">请求头</param>
        /// <param name="cancellationToken">取消令牌</param>
        /// <returns>响应数据</returns>
        Task<T?> PostAsync<T>(string url, object? data = null, Dictionary<string, string>? headers = null, CancellationToken cancellationToken = default);

        /// <summary>
        /// 发送POST请求并返回字符串
        /// </summary>
        /// <param name="url">请求URL</param>
        /// <param name="data">请求数据</param>
        /// <param name="headers">请求头</param>
        /// <param name="cancellationToken">取消令牌</param>
        /// <returns>响应字符串</returns>
        Task<string> PostStringAsync(string url, object? data = null, Dictionary<string, string>? headers = null, CancellationToken cancellationToken = default);

        /// <summary>
        /// 发送PUT请求
        /// </summary>
        /// <typeparam name="T">响应数据类型</typeparam>
        /// <param name="url">请求URL</param>
        /// <param name="data">请求数据</param>
        /// <param name="headers">请求头</param>
        /// <param name="cancellationToken">取消令牌</param>
        /// <returns>响应数据</returns>
        Task<T?> PutAsync<T>(string url, object? data = null, Dictionary<string, string>? headers = null, CancellationToken cancellationToken = default);

        /// <summary>
        /// 发送DELETE请求
        /// </summary>
        /// <typeparam name="T">响应数据类型</typeparam>
        /// <param name="url">请求URL</param>
        /// <param name="headers">请求头</param>
        /// <param name="cancellationToken">取消令牌</param>
        /// <returns>响应数据</returns>
        Task<T?> DeleteAsync<T>(string url, Dictionary<string, string>? headers = null, CancellationToken cancellationToken = default);

        /// <summary>
        /// 发送表单数据POST请求
        /// </summary>
        /// <typeparam name="T">响应数据类型</typeparam>
        /// <param name="url">请求URL</param>
        /// <param name="formData">表单数据</param>
        /// <param name="headers">请求头</param>
        /// <param name="cancellationToken">取消令牌</param>
        /// <returns>响应数据</returns>
        Task<T?> PostFormAsync<T>(string url, Dictionary<string, string> formData, Dictionary<string, string>? headers = null, CancellationToken cancellationToken = default);

        /// <summary>
        /// 上传文件
        /// </summary>
        /// <typeparam name="T">响应数据类型</typeparam>
        /// <param name="url">请求URL</param>
        /// <param name="filePath">文件路径</param>
        /// <param name="fieldName">字段名称</param>
        /// <param name="additionalData">附加数据</param>
        /// <param name="headers">请求头</param>
        /// <param name="cancellationToken">取消令牌</param>
        /// <returns>响应数据</returns>
        Task<T?> UploadFileAsync<T>(string url, string filePath, string fieldName = "file", Dictionary<string, string>? additionalData = null, Dictionary<string, string>? headers = null, CancellationToken cancellationToken = default);

        /// <summary>
        /// 下载文件
        /// </summary>
        /// <param name="url">文件URL</param>
        /// <param name="savePath">保存路径</param>
        /// <param name="headers">请求头</param>
        /// <param name="cancellationToken">取消令牌</param>
        /// <returns>是否成功</returns>
        Task<bool> DownloadFileAsync(string url, string savePath, Dictionary<string, string>? headers = null, CancellationToken cancellationToken = default);

        /// <summary>
        /// 发送原始HTTP请求
        /// </summary>
        /// <param name="method">HTTP方法</param>
        /// <param name="url">请求URL</param>
        /// <param name="content">请求内容</param>
        /// <param name="headers">请求头</param>
        /// <param name="cancellationToken">取消令牌</param>
        /// <returns>HTTP响应消息</returns>
        Task<HttpResponseMessage> SendAsync(HttpMethod method, string url, HttpContent? content = null, Dictionary<string, string>? headers = null, CancellationToken cancellationToken = default);
    }
}